home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / cmds / fsstat.man < prev    next >
Encoding:
Text File  |  1992-05-28  |  11.4 KB  |  238 lines
  1. ' $Header: /sprite/src/cmds/fsstat/RCS/fsstat.man,v 1.6 92/05/28 16:33:44 kupfer Exp $ SPRITE (Berkeley)
  2. .so \*(]ltmac.sprite
  3. .HS FSSTAT cmds
  4. .BS
  5. .SH NAME
  6. fsstat \- Print filesystem statistics
  7. .SH SYNOPSIS
  8. .nf
  9. \fBfsstat \fR[\fB\-H\fR]
  10. \fBfsstat -F \fR[\fB-d \fR[\fB-S \fInumSizes\fR] [\fB-T\fI numTimes\fR]]
  11. .SH OPTIONS
  12. .IP "\fB\-H\fP" 14
  13. Print kernel version and uptime information before statistics.
  14. .IP "\fB\-F\fP" 14
  15. Print file I/O and deletion statistics.
  16. .IP "\fB\-d\fP" 14
  17. Print histogram of file sizes and ages at deletion.
  18. .IP "\fB\-S \fInumSizes\fP" 14
  19. The number of sizes to print in the histogram
  20. .IP "\fB\-T \fInumTimes\fP" 14
  21. The number of times to print in the histogram
  22. .BE
  23. .SH INTRODUCTION
  24. This prints out the various statistics kept by the filesystem.
  25. The stats are printed in several groups
  26. that correspond roughly to sub-structs in the Fs_Stat datatype defined
  27. in \fB<kernel/fsStat.h>\fR.
  28. The following sections decribe statistics by section as printed
  29. by \fBfsstat\fR.  Obvious fields are not explained.
  30. .LP
  31. \fBBlock Cache Statistics.\fP
  32. The BLOCKS line counts 4 Kbyte cache blocks.  The first number is the
  33. current number of blocks; the rest are minimum, maximum, etc.
  34. The two numbers in the ``max'' field are the current maximum
  35. and the physical maximum (in parens).
  36. ``free'' is the number of blocks with no data in them.
  37. There are different kinds of hits on a cache block:
  38. ``dr_hits'' are hits on a dirty block,
  39. ``cl_hits'' are hits on a clean block,
  40. ``p-hits'' are write hits on a partially filled block.
  41. ``p-misses'' are write misses on a partially filled block.
  42. .LP
  43. The WRITETHRU line has percentages which are relative to
  44. the number of WRITE blocks reported on the WRITE line.
  45. Virtual memory page-outs are not included in the WRITE blocks,
  46. but are counted in the ``vm'' field of WRITETHRU.
  47. Thus WRITETHRU can be bigger than WRITE if there is lots of paging.
  48. ZERO FILL has two numbers by write, one for zero fills because
  49. the read of the existing block was less than 4K,
  50. the second for zero fills because the write was less than 4K.
  51. The ``append'' field is probably obsolete.
  52. The ``over'' field is for blocks that were overwritten.
  53. .LP
  54. For READ AHEAD the ``all in cache'' field has two numbers:
  55. one for the number of times we asked if all the blocks were already
  56. in the cache, the second for the number of times they were.
  57. Read ahead is currently implemented by scheduling a background
  58. process.  This has too much overhead and so read ahead is usually disabled.
  59. FRAGMENT upgrades are fragments that got promoted to a full block.
  60. .LP
  61. The VM line has four numbers.  The first is
  62. the number of times VM asked FS for a page.  The ``we tried'' number counts
  63. the number of requests where it was possible for the FS to give away a
  64. page (non-empty free list, and more than the minimum number of blocks
  65. in the cache).
  66. The ``gave up'' number counts the number of times the FS actually gave
  67. away a page.  The ``pitched'' field is the number of cache blocks that were
  68. discarded (put at the front of the LRU list) because they duplicated
  69. VM-managed blocks.
  70. .LP
  71. The ALLOC line indicates where cache blocks were obtained:
  72. ``free'' means the free list,
  73. ``new'' means newly created blocks,
  74. ``lru'' means blocks replaced via the least-recently-used algorithm,
  75. ``part free'' means the partially free list, i.e. those (8K) pages
  76. which had one valid (4K) block and one free block.
  77. .LP
  78. \fBName Cache Statistics\fP.
  79. The ``size'' indicates how many entries are kept in the hash table.
  80. The other fields indicate the number of accesses and the hit ratio.
  81. File deletion removes entries so the number of replacements is not the
  82. complement of the number of hits.
  83. .LP
  84. \fBBlock Allocation Statistics\fP.
  85. The CYLINDERS line indicates how many cylinders were searched
  86. to find one with free blocks.
  87. The ``hashes'' field is the number of hashes done to choose
  88. a cylinder for a file.  ``bit-searches'' is the number
  89. of bytes scanned in the free block bitmask.
  90. The FRAGS line concerns block fragments.
  91. ``fr->block'' is the number of free fragments collapsed into blocks.
  92. ``block->fr'' is the number of free blocks broken into fragments.
  93. ``upgrades'' is the number of fragmented blocks promoted to full blocks.
  94. ``bad hints'' is the number of fragment list entries that proved wrong.
  95. The kernel keeps a free list for each fragment size,
  96. but growth of an allocated fragment can invalidate entries in these lists.
  97. .LP
  98. \fBFile Handle Statistics\fP.
  99. The internal data structure kept for each file is known as
  100. a ``file handle''.  Handles are ``installed'' into a hash table initially.
  101. ``create'' indicates the number of times the handle was not already
  102. present.  ``version'' indicates the number of existing handles that
  103. were out-of-date due to attribute changes.  ``flush'' indicates the number
  104. of times the cached blocks (if any) for a file were invalid when its
  105. handle was installed.  Uncachable files are also counted by this field.
  106. Existing handles may also be ``fetched'',
  107. ``locked'', and then ``released''.  There are two numbers by the
  108. ``lock'' field, but one is obsolete and is always zero.
  109. The ``wait'' field is the number of locks that had to wait.
  110. Information about handle LRU replacement is printed later
  111. (for historical reasons) after Object information.
  112. .LP
  113. \fBSegment\fP.
  114. The VM sticky segment information is tucked away after the
  115. file handle statistics.  Text segments along with their page tables
  116. are cached, and this line counts the hit ratio for this feature.
  117. .LP
  118. \fBPrefix Statistics\fP.
  119. This counts the number of ``absolute'' and ``relative'' file name lookups.
  120. ``redirect'' is the number of lookups that bounced from one server to
  121. another.  Symbolic links back to the root cause a bounce,
  122. as can ascending via "..", as can descending through remote links.
  123. ``loop'' is the number of symbolic link loops detected.
  124. ``timeout'' is the number of lookups that failed because of a
  125. timeout to the server.
  126. ``stale'' is the number of lookups that failed because of stale
  127. handles for the starting point of the lookup.
  128. ``found'' is the number of prefix table entries found via broadcast.
  129. .LP
  130. \fBInternal Fragmentation\fP.
  131. This counts the bytes wasted due to the use of 4 Kbyte blocks in the cache.
  132. There are two lines, one in comparision to a cache with variable sized blocks,
  133. the other relative to a cache with 1K byte blocks.
  134. .LP
  135. \fBCount of Calls\fP.
  136. This is the number of open calls made by local processes,
  137. i.e. remote requests are not counted.  (FIX!)
  138. The opens are broken into opens for reading, writing, and read-write.
  139. The number of set attribute calls is also given.
  140. .LP
  141. \fBBytes\fP.
  142. This section gives statistics on a per-byte basis of
  143. cache traffic, network traffic, disk traffic, and raw device traffic.
  144. .LP
  145. \fBObjects\fP.  Counts of the number of different kinds of objects
  146. occur next to the two lines labeled \fBOBJECTS\fP.
  147. ``stream'' is the number of top-level open file descriptors there are.
  148. There is one per open system call, plus there are shadow streams on I/O
  149. servers.  The ``(clt)'' field is the number of stream clients.   This is
  150. the same as the number of streams except during process migration when
  151. a stream may be shared by different hosts.
  152. There is also a ``ioClt'' field that is the number of entries in
  153. object descriptor client lists.  Devices, pseudo-devices, files,
  154. and directories all have lists of the clients using them.
  155. The rest of the fields are for the different kinds of objects
  156. implemented by the file system.  There is one object descriptor
  157. kept for each object in use, including those that are not open
  158. but do have data in the cache.
  159. The fields ``file'', ``dir'', ``rmtFile'', ``pipe'', ``dev''
  160. correspond to the obvious object.  ``pdevCtrl'' corresponds to
  161. the number of active pseudo-devices.
  162. There will be one of these on the file server with the
  163. pseudo-device name and one on the host running the pseudo-device process.
  164. ``pdev'' corresponds to pseudo-device connections, of which there
  165. can be more than one to any particular pseudo-device.
  166. There are two internal object descriptors for a pseudo-device connection,
  167. one for the client and one for the server.
  168. The total number of object descriptors (including streams and 2 per ``pdev'')
  169. is given in the ``Total'' field.
  170. .LP
  171. \fBHandles\fP.  More statistics on the handle table are printed after
  172. the object information on the line labeled \fBHANDLES\fP.
  173. ``Handle'' is the kernel venacular for
  174. ``object-descriptor'', so there is one handle per object.  The current
  175. maximum number of handles is given by the ``max'' field.  The table will grow
  176. if necessary.  The current number of handles is given by the ``exist''
  177. field, and should match the ``Total'' field of the object counts.
  178. The ``limbo'' field is a count of handles that have been removed
  179. from the table, but have not had their memory de-allocated.
  180. ``scans'' is the number of times the table was searched in LRU order
  181. to replace a handle because the table was at the maximum size.
  182. ``looks'' is the number of handles that were examined and found in-use
  183. and so not available for replacement.  ``scav'' was the number that
  184. were reclaimed, or scavenged.  Of these, the number that were
  185. directories is listed in the ``(dirs)'' field.  One handle is replaced
  186. per scan, and if none can be replaced then the table is allowed to grow.
  187. Thus the difference between ``scans'' and ``scav'' is the number of
  188. times the table had to grow.  (The table starts at 400 handles
  189. and grows in increments of 25.  These constants might be different
  190. on your system.)
  191. .LP
  192. \fBRecovery\fP.  Failure recovery statistics are printed on two lines
  193. labeled \fBRECOVERED\fP.  The first line contains the number of
  194. times the re-open protocol was gone through with a server (``times'').
  195. This line also lists the number of operations that failed due to
  196. a communication failure and registered a need for recovery (``wants''),
  197. and the number of these operations that were retried successfully
  198. after recovery (``ok''),
  199. the number that could not be retried due to failed recovery (``bad''),
  200. and the number that were aborted before recovery was attempted (``abort'').
  201. The second line summaries how many handles were re-opened (``handles''),
  202. the number that could not be reopened (``failed''), and the
  203. number that had communication failures during the re-open attempt
  204. (``timed out'').
  205. .LP
  206. \fBClient Recovery\fP.  The line labeled \fBCLIENTS\fP appears on
  207. servers.  The field ``crashed'' counts how many of the server's
  208. clients have crashed.  The field ``reopened'' counts how many clients
  209. reopened files at the server after the server rebooted.
  210. .LP
  211. \fBFile type I/O and deletion statistics\fP.
  212. If the \fB-F\fP option is specified then the cache and disk
  213. traffic due to different kinds of regular files is given,
  214. plus the number of bytes deleted.  The type is the
  215. ``userType'' in the file descriptor, which is a user-settable attribute.
  216. The types are ``temp'', for files in the \fB/tmp\fP directory,
  217. ``swap'' for swap files,
  218. ``obj'' for .o files,
  219. ``bin'' for binary executables,
  220. and ``other'' for all other kinds of files.
  221. If the histogram option (\fB-d\fP) is specified the deletion
  222. info is further broken
  223. down and presented in a histogram of cumulative bytes deleted
  224. verses file age and type.
  225. .SH BUGS
  226. Somebody needs to look at each of the numbers given by this program
  227. and verify whether (a) the number still makes sense and (b) the number
  228. is correctly documented.
  229. .LP
  230. Some of the percentage figures are at best misleading.  For example,
  231. the vm ``percentage'' on the \%WRITETHRU line does not mean ``what
  232. fraction of the data blocks written were due to VM,'' nor does it mean
  233. ``what fraction of write requests resulted in VM pageouts.''
  234. .SH "SEE ALSO"
  235. fscmd, prefix, rpccmd
  236. .SH KEYWORDS
  237. file system, cache, statistics
  238.